.\" This is part of a set of commands and information released under the
.\" OpenCALEA Project.  http://www.opencalea.org/
.\" 
.\" OpenCalea is distributed under the terms of the modified BSD license:
.\" 
.\" /*
.\" * Copyright (c) 2007, Merit Network, Inc.
.\" * All rights reserved.
.\" *
.\" * Redistribution and use in source and binary forms, with or without
.\" * modification, are permitted provided that the following conditions are met:
.\" *
.\" *     * Redistributions of source code must retain the above copyright
.\" *       notice, this list of conditions and the following disclaimer.
.\" *     * Redistributions in binary form must reproduce the above copyright
.\" *       notice, this list of conditions and the following disclaimer in the
.\" *       documentation and/or other materials provided with the distribution.
.\" *     * Neither the name of Merit Network, Inc. nor the names of its
.\" *       contributors may be used to endorse or promote products derived
.\" *       from this software without specific prior written permission.
.\" *
.\" * THIS SOFTWARE IS PROVIDED BY MERIT NETWORK, INC. ``AS IS'' AND ANY
.\" * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" * DISCLAIMED. IN NO EVENT SHALL MERIT NETWORK, INC. BE LIABLE FOR ANY
.\" * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\" */
.TH "tap" "8" "svn-20070503" "The OpenCALEA Project" "OpenCALEA"
.SH "NAME"
.LP 
tap \- OpenCALEA network tap
.SH "SYNTAX"
.LP 
\fBtap\fR
[\fB\-f\fR \fIconfig\-file\fR]
[\fB\-u\fR \fIuser\fR]
[\fB\-g\fR \fIgroup\fR]
[\fB\-i\fR \fIinterface\fR]
[\fB\-d\fR \fIdestination\fR]
[\fB\-p\fR \fIdf\-port\fR]
[\fB\-c\fR \fIcontent\-type\fR]
[\fB\-x\fR \fIcontent\-id\fR]
[\fB\-y\fR \fIcase\-id\fR]
[\fB\-z\fR \fIiap\-system\-id\fR]
[\fB\-v\fR [\fI...\fR]]
[\fB\-D\fR \fIdebug\-file\fR]
[\fB\-l\fR \fIlog\-level\fR]
[\fB\-L\fR \fIlogfile\fR]
[\fB\-h\fR]
[\fIcapture\-filter\fR]
.SH "DESCRIPTION"
.LP 
This program is a network tap (packet sniffer) from the OpenCALEA project.  It can be invoked to collect CACmII (Content Associated Communications Identifying Information) and CmC (Communication Content) for an intercept subject, which is sent to a running \fBdf_collector\fR(8) program somewhere in the network.
.LP 
We currently use the same content format for an Internet data tap (T1.IAS standard) and a Voice intercept (T1.678 standard), ie. a \fICC\-APDU\fR structure.  More formats will likely be added in the future.  The \fB\-c\fR switch will parse other formats, but they're not there yet.
.LP 
\fBtap\fR(8) can be invoked by itself, but is normally started by the \fBtap_controller\fR(8) program.  See \fBtap_controller\fR(8) for more information.
.SH "OPTIONS"
.LP 
\fBtap\fR(8) can run with no command line options, configured entirely by a config file.  In the absence of any config file, you must specify the content type and other options required by that content type.

.TP 
\fB\-f\fR \fIconfig\-file\fR
Specifies an alternate \fIconfig file\fR.

.br 
Default: see FILES below.

.TP 
\fB\-u\fR \fIuser\fR
Specifies the \fIuser\fR to change to if run as root.

.br 
Default: \fBUser\fR from config file or \fBcalea\fR.

.TP 
\fB\-g\fR \fIgroup\fR
Specifies the \fIgroup\fR to change to if run as root.

.br 
Default: \fBGroup\fR from config file or \fBcalea\fR.

.TP 
\fB\-i\fR \fIinterface\fR
Specifies the network \fIinterface\fR to capture on.

.br 
Default: \fBInterface\fR from config file or system dependent.

.TP 
\fB\-d\fR \fIdestination\fR
Specifies the destination host to send CmII and CmC messages to.
This host should be running \fIdf_collector\fR(8).

.br 
Default: \fBDF_Collector\fR from config file or \fBlocalhost\fR (127.0.0.1).

.TP 
\fB\-p\fR \fIdf\-port\fR
Specifies the \fIport\fR on \fIdestination\fR above where \fBdf_collector\fR(8) is listening for data.

.br 
Default: \fBDF_Port\fR from config file or \fB41805\fR.

.TP 
\fB\-c\fR \fIcontent\-type\fR
Specifies the type of content to send.
Valid values of \fIcontent\-type\fR are:

.br 
\fBvop\-cc\fR  Send ATIS VOP content (CC\-APDU).
.br 
\fBias\-cmii\fR  Send ATIS IAS CACmII (Packet\-Data\-Header\-Report).
.br 
\fBias\-cmc\fR  Send ATIS IAS CACmII and CmC (IAS\-CC\-APDU).
.br 
\fBias\-cmc\-udp\fR  Send ATIS IAS CACmII and CmC (Annex D.3.1 udp encapsulation).
.br 
\fBraw\fR  Send captured packets, sans link layer headers (no formatting).
.br 
\fBraw\-full\fR  Send captured packets with link layer headers (no formatting).

.br 
Default: \fBContent_Type\fR from config file.
.br 
Required: yes.

.TP 
\fB\-x\fR \fIcontent\-id\fR
Specifies the Content ID; placed in CmII and CmC messages.

.br 
Default: \fBContentID\fR from config file.
.br 
Required: For all ATIS content types (vop\-* and ias\-*).

.TP 
\fB\-y\fR \fIcase\-id\fR
Specifies the Case ID; placed in CmII and CmC messages.

.br 
Default: \fBCaseID\fR from config file.
.br 
Required: For all ATIS content types (vop\-* and ias\-*).

.TP 
\fB\-z\fR \fIiap\-system\-id\fR
Specifies the IAP System ID for this system; placed in CmII and CmC messages.

.br 
Default: \fBIAPSystemID\fR from config file.
.br 
Required: For all ATIS content types (vop\-* and ias\-*).

.TP 
\fB\-v\fR [\fI...\fR]
Enable debugging (\fB\-d\fR was taken).  Use multiple times to increase verbosity.

.br 
Default: \fBDebug_Level\fR from config file or off.

.TP 
\fB\-D\fR \fIdebug\-file\fR
Specifies where to debug to.
Valid values are \fBstdout\fR, \fBstderr\fR, \fBsyslog\fR or a \fIfilename\fR.

.br 
Default: \fBDebug_Destination\fR from config file or \fBsyslog\fR.

.TP 
\fB\-l\fR \fIlog\-level\fR
Specifies log level.
\fIlog\-level\fR should be a numeric value from \fB1\fR (least) to \fB5\fR (most).

.br 
Default: \fBLog_Level\fR from config file or \fB1\fR.

.TP 
\fB\-L\fR \fIlogfile\fR
Specifies where to log to.
Valid values are \fBstdout\fR, \fBstderr\fR, \fBsyslog\fR or a \fIfilename\fR.

.br 
Default: \fBLog_Destination\fR from config file or \fBsyslog\fR.

.TP 
\fB\-h\fR
Prints help / usage message.

.TP 
\fIcapture\-filter\fR
Specify packet capture filter in libpcap syntax.
See \fItcpdump\fR(8) man page for syntax.

.br 
Default: \fBPCAP_Filter\fR from config file or none.
.SH "FILES"
.LP 
.TP 
\fI/etc/opencalea/opencalea.conf\fP
OpenCALEA shared config file
.TP 
\fI/etc/opencalea/tap.conf\fP
\fItap\fR(8) specific configuration
.SH "EXAMPLES"
.LP 
To run \fItap\fR(8) intercepting voice (VOP) content for ip address 123.45.67.89, with the minimum of \fIcontent\-id\fR and \fIcase\-id\fR, and sending to \fIdf_collector\fR(8) running on 192.168.0.20:
.LP 
\fBtap\fR
\fB\-x\fR "Intercept Subject .89" \fB\-y\fR Case\-ID\-001
\fB\-c\fR vop\-cc
\fB\-d\fR 192.168.0.20  host 123.45.67.89
.LP 
To run \fItap\fR(8) capturing all data on the "eth2" \fIinterface\fR, \fIdebug\fRging to standard out, sending CACmII (not content) to \fIdf_collector\fR(8) running on localhost:
.LP 
\fBtap\fR
\fB\-x\fR x \fB\-y\fR y 
\fB\-c\fR ias\-cmii
\fB\-i\fR eth2 \fB\-vvv \-D\fR stdout
.LP 
or
.LP 
\fBtap\fR
\fB\-x\fR x \fB\-y\fR y 
\fB\-c\fR ias\-cmii
\fB\-i\fR eth2 \fB\-vvv \-D\fR stdout \fB\-d\fR localhost\fR
.LP 
To run \fItap\fR(8) capturing both CACmII and CmC traffic to/from mac address "00:11:22:33:44:55", \fIlog\fRging to a file, with \fIdf_collector\fR(8) running on \fIport\fR 1234 on host df\-collector.mydomain.com:
.LP 
\fBtap\fR
\fB\-x\fR x \fB\-y\fR y
\fB\-c\fR ias\-cmc
\fB\-l\fR 5 \fB\-L\fR /tmp/tap.log
\fB\-n\fR 1234 \fB\-d\fR df\-collector.mydomain.com
ether host 00:11:22:33:44:55

.SH "AUTHORS"
.LP 
Manish Karir <mkarir@merit.edu>
.br 
Jesse Norell <jesse@kci.net>
.br 
Norman Brandinger <norm@goes.com>
.SH "SEE ALSO"
.LP 
\fItap_controller\fR(8), \fIdf_collector\fR(8), \fIopencalea\fR(8)
.LP 
\fItap.conf\fR(5), \fIopencalea.conf\fR(5)
.LP 
http://www.opencalea.org/
.SH "STANDARDS"
.LP 
OpenCALEA conforms to the following standards, which are intended to provide "safe harbor" as per Section 107 of \fICALEA, Public Law 103\-414\fR.
.LP 
\fIATIS\-1000013.2007,
Lawfully Authorized Electronic Surveillance (LAES) for Internet Access and Services.\fR
.LP 
\fIATIS\-PP\-1000678.2006,
Lawfully Authorized Electronic Surveillance (LAES) for Voice over
Packet Technologies in Wireline Telecommunications Networks, Version 2.\fR
.LP 
OpenCALEA is following the development of the WISPA standard for data capture and will add support when possible.
.SH "SECURITY"
.LP 
\fItap\fR(8) is effectively a packet sniffer designed to ship captured traffic to an arbitrary location; ie. a prime target for misuse.  It needs to be run either by root or a user with appropriate (OS specific) capabilities/setup to access bpf or open raw devices.  Please use \-u and \-g to change the user/group id once started.
.SH "BUGS"
.LP 
Please report all bugs to the OpenCALEA mailing list at:
.IP 
<opencalea@merit.edu>
